Extract a plot_types/ package — one module per plot type (#83, #91) - #93

The second half of the split: config keys, validation, reference rewriting
and xlsx row interpretation join the capabilities in `plot_types/<name>/
schema.py`. `constants.py` gives up `SpectrogramConfig`, `PsdConfig` and the
three derived section keys; `KNOWN_SECTION_KEYS` declares only the keys no plot
type owns, and the parser unions each registered type's own section key onto it,
so a new plot type can no longer make a valid config warn "Unknown key".

Six spellings of the derived-plot list become one. `plot_assembly`'s three
qualifiers and `other`'s three were the same shape-walks over the same shapes,
differing only in the leaf op -- resolve-then-prefix `datasource::` versus
blind-prefix `<stem>::`. Each shape is now walked once, by the type that owns
it, through `map_refs(config, map_ref)`.

The xlsx reader transcribes and the plot type interprets: sheet name, required
columns and row->config mapping move to `schema.py`, so the spreadsheet columns
and the JSON keys -- one schema in two spellings -- are declared where they
cannot drift apart. The cell coercions stay in the reader and are lent to a
schema through `CellReader`, since the reader imports every schema to find its
sheet.

`loop` gains the validation the other two had. It had none, which is why it was
absent from the parser's lists rather than merely forgotten: wrong arity, a
non-list entry and a non-string member were all silent before, and a loop
naming one signal simply failed to appear. A malformed per-file loop now costs
one plot instead of the whole file -- scoping it used to assume a list and
raise inside `other`'s per-file handler.

Three import-time snapshots are gone, found by the fake-plot-type test:
`plot_assembly` bound `BUILDERS` by value, and both the section-key set and the
derived-plot tuple were computed at import. Each was a second source of truth
for a collection the registry owns.

Closes the work of #83. 1060 tests pass; the demo database_options.json still
regenerates byte-identical from its .xlsx.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The registry already refuses a plot type missing half its code, and the
snapshot suite covers what it draws. Neither notices a type that imports,
validates, renders — and is configured nowhere and described nowhere.

Two guards for that gap, both green on the three existing types:

- every registry.DERIVED type is configured in the demo config, so a new
  type ships exercised against demo_patient rather than only in unit tests
- every registry.DERIVED type has a tutorial heading and a CONTEXT.md
  glossary term

The doc guard is a weaker category than its neighbours in
test_example_assets.py, which only ever compare registry-derived sets
against disk-derived ones. It anchors on headings and bold glossary terms
rather than a search of the prose: "loop" appears throughout the tutorial
as the datasource loop, a loop subplot's height, multi-cycle loops — so a
body search would report green for a type nobody had documented. The
accepted spellings come off the schema (NAME, SECTION_KEY, SHEET_NAME),
which is what lets `loops` match `loop` without hardcoding a plural.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Mirrors /new-datasource, but with a different job. That skill is largely a
checklist because a datasource has coordinated pieces easy to forget; here
the registry already makes a forgotten half an import-time crash, so a
checklist would be guarding a door that is already locked.

What the code cannot decide is what the skill covers:

- the gate. A plot type earns a package only by declaring a *delta* from
  time_series. Four flags discriminate — TIME_AXIS, GRID_LAYOUT,
  HAS_COLORBAR, POINT_TIMESTAMPS. RESAMPLED and UNIFIED_HOVER are False on
  all three existing types, so they say "I am derived" rather than what
  makes one different, and gating on them would accept anything. The gate
  falls out of the classification rather than preceding it: the four
  answers that pass it are the four that configure the scaffold.

- the maths, as a blocking checkpoint. plot.py is an adapter —
  spectrogram_from_signal calls spectral.spectrogram() and spends its body
  wrapping the result — so the skill scaffolds the adapter and never
  invents the transform. Declaring the refusal exception is required:
  plot_assembly grades an undeclared one as a crash with a full traceback.

When no flag is a delta the skill names the hole and stops rather than
routing anywhere. New maths drawn against time, sharing a zoom with its
source, has no home today — every builder sets its own plot_type=, and
nothing builds a derived Signal that renders as a time-series. Forcing it
into a plot type would park it on a page section away from its source.

Vendors mattpocock/skills' grilling verbatim (MIT, LICENSE.txt alongside),
which the skill invokes at the gate and at the maths. Both it and
/new-plot-type join the CLAUDE.md skills table.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The package had two answers to "how does this plot type behave?". Rendering
was pushed — a builder installs a RenderSpec on the Signal it constructs, so
to_plotly_trace never reaches for a plot type's module. Capabilities were
pulled — signal_container held a plot_type string and asked the registry,
`if self.plot_type in plot_types.GRID_LAYOUT`, in eight places.

The pull was justified by an import cycle: signal_container is reachable
from a half-initialised datasource package, so a plot.py importing Signal
back out of it would fail for some entry points and not others. That fear
drove the schema.py/plot.py split, the registry.py/builders.py split, a
find_spec probe instead of an import, and RenderSpec itself.

Tested rather than assumed: making registry import all three plot.py modules
at module scope broke no entry point. Two things absorbed it — the eager
`from clinical_scope.wrapper import ...` in __init__.py fixes module order
for every entry point, and signal_container bound the registry as a *module
object*, touching attributes only at call time. Real on the dependency
graph, inert in practice, and it had grown a second pattern for a problem
RenderSpec already solved.

The cost was never the cycle. It was that one question had two shapes, and
the string-keyed one accumulated hand-maintained duplicates: square_plot was
a second spelling of GRID_LAYOUT, kept in sync by nothing — the fake plot
type in the test suite declared one and not the other and rendered wrong.

So a Signal now carries the schema class itself. plot_options.schema and
PlotModel.schema hold type[PlotTypeSchema]; plot_type survives as a
read-only property returning schema.NAME, for logs, figure titles and Dash
stores, which is why every `model.plot_type == "loop"` read is untouched.
signal_container imports nothing from plot_types but base, asserted by
test_boundaries.

Two things could not simply be pushed:

- page order is a fact about the collection, not about one type, so
  assign_plot_model left PlotModel and became plot_assembly.
  assemble_plot_models — the module named for assembly now does both steps
- a plot type that crossed a Dash store as JSON has only its name left, so
  registry.schema_for is the single string-to-schema conversion. An
  unregistered name resolves to Unknown, every capability off; deliberately
  not the time_series defaults, which would let a typo render plausibly

That deletes the six capability frozensets, the globals() reflection check
that policed them, square_plot on both PlotOptions and PlotModel, and the
find_spec probe — builders.py already checks the same thing, keyed by the
schema rather than by a path.

The schema.py/plot.py and registry.py/builders.py splits stay, re-justified.
The cycle argument is dead but a better one survives: schema.py imports only
validation, so checking a config never loads numpy and plotly. "The config
layer must not import the render layer" is a rule a reader can hold; the
import-order argument it replaces is not.

Alongside, from the same review:

- data_callbacks read plot_model.name for RESAMPLED while reading
  plot_model.plot_type for POINT_TIMESTAMPS. They agree only because
  __post_init__ aliases name to the plot type, and name is also a Dash
  component id, so a real title would have silently broken resampling
- spectrogram and psd returned no issue for a non-dict entry, which is the
  validates-cleanly-renders-nothing failure the package exists to kill; loop
  already reported it properly
- Data.loop_time_axis is now point_time_axis, matching the POINT_TIMESTAMPS
  capability that gates it — data_callbacks reads it inside a branch on that
  generic flag, so a second timestamped type would have had to populate a
  field named after loops
- the schema/builder seam was typed Any throughout. PlotBuilder.build and
  read_sheet now have real signatures behind `if TYPE_CHECKING`, which never
  executes and so closes no cycle. entries/entry/config stay Any and say so:
  they are raw user JSON, and narrowing them is validate()'s job
- CellReader gains text() and pair(), absorbing fifteen str(row.get()).strip()
  copies and the db_min/db_max rule that was written twice with two different
  messages. The row loop is left alone — psd's rows fan out into several
  groups, so a shared template would have one and a half users
- ValidationIssue.unknown_keys replaces six hand-rolled copies of one message

A regression test covers the square_plot bug directly: a grid type with a
single subplot must still get a figure width, from GRID_LAYOUT and nothing
else. The fake plot type is where it belongs, since that is the type that
had it wrong.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

registry.py and builders.py were one roster split in two: the first held
every schema, the second held what builds each. They were separated because
a plot.py imports signal_container, which imported registry — folding them
together would have closed a cycle.

That cycle is gone. Nothing outside plot_types reaches the registry for a
capability any more, so signal_container imports only plot_types.base, and
registry is free to import the render halves it is a roster of.

The justification the split had left was that importing the config layer
would no longer be cheap. Measured, and it was already untrue:

    >>> import clinical_scope.database_options_parser
    heavy modules pulled in: ['plotly', 'numpy']
    plot.py modules loaded : [loop.plot, psd.plot, spectrogram.plot]

clinical_scope/__init__.py eagerly imports wrapper, so every plot.py is
loaded before the parser's first line runs. No entry point ever saw the
cheap config layer the split was protecting.

So registering a plot type is now two adjacent lines in one file, AVAILABLE
and BUILDERS, and the two completeness checks became one: a derived type
with no builder raises from the same place a duplicate name does, rather
than from a second module the first knows nothing about.

BUILDERS stays keyed by the schema class rather than by name, so a builder
cannot be filed under a spelling no type answers to.

The plot modules are imported as _loop_plot rather than _loop: the alias
names a module inside the package, not the package, and _loop.BUILDER read
as though the loop package exported one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

"Schema" described one third of what the file holds. Alongside the config
grammar — validate, map_refs, read_sheet — it carries the type's identity
(NAME, SECTION_KEY) and its six capability flags, which are booleans about
how the type *draws* and are the file's most-read content. A file named for
configuration was the wrong place to look for them, which is part of why
"may signal_container import this?" stayed confusing for so long.

The word was also already spent twice. cst.UserOptions.LoopsPerRow and its
siblings are called schema classes, and data_callbacks builds a Dash
"schema-registry" mapping component ids to widget schemas — genuinely a
schema, and unrelated. Three meanings, and the plot type had the weakest
claim on the word.

So: schema.py becomes definition.py, PlotTypeSchema becomes
PlotTypeDefinition, plot_options.schema becomes plot_options.definition, and
registry.schema_for becomes definition_for. It reads correctly at the use
site — self.definition.GRID_LAYOUT is "this plot type's definition says it
is a grid" — where self.schema.GRID_LAYOUT read as a category error.

Mechanical, but not blindly: the other two meanings were left alone, and
several sentences the rename would have degraded were rewritten rather than
carried over. "The sheet columns and the JSON keys are one schema in two
spellings" was right the first time and became "one grammar in two
spellings"; "the parser reaches every schema" became "every plot type".

The files stay split. The layering reason is gone — the previous commit
showed the config half is never loaded alone — but psd is 302 lines of
spreadsheet row accumulation and group resolution against 154 lines of a
Welch call and axis wiring, and someone asking why a row did not become a
plot is not the person asking why a PSD is scaled wrong. It also keeps the
shape a registered module already has here: datasource/sources/<name>/ is
options.py plus find_load_format.py, the same declarative half and working
half.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>